---
title: Solución de problemas
description: ¿Necesitas ayuda? ¿Estás atascado? Nosotros te ayudamos.
i18nReady: true
---

Astro provee muchas herramientas diferentes para ayudar a solucionar y debuggear los problemas en tu código.

## Consejos y trucos

### Depuración con `console.log()`

`console.log()` es un método sencillo pero popular para depurar tu código de Astro. Donde escribas tu declaración `console.log()` determinará dónde se imprimirá la salida de depuración:

```astro
---
console.log('¡Hola! Soy el servidor. Esto se registra en la terminal donde se está ejecutando Astro.');
---
<script>
console.log('¡Hola! Soy el cliente. Esto se registra en la consola de desarrollo del navegador.');
</script>
```

Una declaración `console.log()` en el frontmatter de Astro siempre enviará su salida a la **terminal** en la que se está ejecutando la CLI de Astro. Esto se debe a que Astro se ejecuta en el servidor y nunca en el navegador.

El código que se escribe o importa dentro de una etiqueta `<script>` de Astro se ejecuta en el navegador. Cualquier declaración `console.log()` u otra salida de depuración se imprimirá en la **consola de tu navegador**.

### Depurando componentes de frameworks

[Componentes de framework](/es/guides/framework-components/) (como React y Svelte) son únicos: se renderizan en el lado del servidor de forma predeterminada, lo que significa que la salida de depuración de `console.log()` será visible en la terminal. Sin embargo, también pueden ser hidratados para el navegador, lo que puede hacer que tus registros de depuración también aparezcan en el navegador.

Esto puede ser útil para depurar las diferencias entre la salida del SSR y los componentes hidratados en el navegador.

### Componente `<Debug />` de Astro

Para ayudarte a depurar tus componentes de Astro, Astro proporciona un componente incorporado [`<Debug />`](/es/reference/api-reference/#debug-) que renderiza cualquier valor directamente en la plantilla HTML de tu componente. Esto es útil para depuración rápida en el navegador sin tener que alternar entre tu terminal y tu navegador.

```astro {2,7}
---
import { Debug } from 'astro:components';
const sum = (a, b) => a + b;
---
<!-- Ejemplo: Muestra {answer: 6} en el navegador -->
<Debug answer={sum(2, 4)} />
```

El componente Debug admite una variedad de opciones de sintaxis para una depuración aún más flexible y concisa:

```astro {2,7-9}
---
import { Debug } from 'astro:components';
const sum = (a, b) => a + b;
const answer = sum(2, 4);
---
<!-- Ejemplo: Los tres ejemplos son equivalentes. -->
<Debug answer={sum(2, 4)} />
<Debug {{answer: sum(2, 4)}} />
<Debug {answer} />
```

## Mensajes de error comunes

Aquí veremos algunos mensajes de error comunes con los que te puedes llegar a cruzar en la terminal, su significado y qué hacer para solucionarlos. Consulta nuestra [guía de referencia de errores completa](/es/reference/error-reference/) para obtener una lista completa de los errores de Astro que puedes encontrar.

### Cannot use import statement outside a module

En componentes de Astro, las etiquetas `<script>` son elevadas (hoisted) y cargadas como [módulos JS](https://developer.mozilla.org/es/docs/Web/JavaScript/Guide/Modules) por defecto. Si has incluido la [directiva `is:inline`](/es/reference/directives-reference/#isinline) o cualquier otro atributo en tu tag, este comportamiento por defecto es eliminado.

**Solución**: Si has añadido atributos a tu tag `script`, también debes agregar el atributo `type="module"` para poder usar declaraciones de importación.

**Estado**: Comportamiento esperado de Astro.

**¿No estás seguro de que este sea tu problema?**
¡Puedes ver si alguien ya ha reportado [este error](https://github.com/withastro/astro/issues?q=is%3Aissue+is%3Aopen+Cannot+use+import+statement)!

### `document` (or `window`) is not defined

Este error ocurre cuando se intenta acceder a `document` o `window` en el lado del servidor.

#### Causas comunes

Los componentes de Astro se ejecutan en el servidor, por lo que no puedes acceder a estos objetos específicos del navegador dentro del frontmatter.

Los componentes de framework se ejecutan en el servidor por defecto, por lo que este error puede ocurrir cuando se accede a `document` o `window` durante la renderización.

**Solución**: Determina el código que llama a `document` o `window`. Si no estás usando `document` o `window` directamente y aún así recibes este error, revisa si algún paquete que estés importando está pensado para ejecutarse en el cliente.

- Si el código está en un componente de Astro, muévelo a una etiqueta `<script>` fuera del frontmatter. Esto le dice a Astro que ejecute este código en el cliente, donde `document` y `window` están disponibles.

- Si el código está en un componente de framework, intenta acceder a estos objetos después de la renderización usando métodos de ciclo de vida (por ejemplo, [`useEffect()`](https://react.dev/reference/react/useEffect) en React, [`onMounted()`](https://vuejs.org/api/composition-api-lifecycle.html#onmounted) en Vue, y [`onMount()`](https://svelte.dev/docs#run-time-svelte-onmount) en Svelte). También puedes evitar que el componente se renderice en el servidor agregando la directiva [`client:only`](/es/reference/directives-reference/#clientonly).

**Estado**: Comportamiento esperado de Astro.

### Expected a default export

Este error puede ser lanzado cuando intentas importar o renderizar un componente inválido, o uno que no funciona de manera correcta. (Este mensaje particular ocurre por la forma en que funciona la importación de componentes de UI en Astro.)

**Solución**: Intenta buscar errores en los componentes que estás intentando importar y renderizar, y asegúrate que están funcionando correctamente. Considera abrir una plantilla de inicio de Astro desde [astro.new](https://astro.new) para intentar solucionar el problema de tu componente en un entorno mas sencillo

**Estado**: Comportamiento esperado de Astro.

### Refused to execute inline script

Es posible que veas el siguiente error en la consola del navegador:

> Refused to execute inline script because it violates the following Content Security Policy directive: …

Esto significa que la [política de seguridad de contenido](https://developer.mozilla.org/es/docs/Web/HTTP/CSP) (CSP) de tu sitio web no permite ejecutar etiquetas `<script>` en línea, las cuales Astro genera por defecto.

**Solución:** Actualiza tu CSP para incluir `script-src: 'unsafe-inline'` para permitir que los scripts en línea se ejecuten. De forma alternativa, puedes usar integraciones de terceros tales como [`astro-shield`](https://github.com/KindSpells/astro-shield) para que generen las cabeceras CSP por ti.

## Problemas comunes

### Mi componente no se renderiza

Primero, comprueba que has **importado el componente** en el [script del componente `.astro`](/es/basics/astro-components/#script-de-un-componente) o en el [frontmatter de `.md`](/es/guides/markdown-content/#usando-componentes-en-mdx).

Luego chequea la declaración de importación:

- Estás realizando la importación desde el lugar correcto? (Revisa la ruta de importación.)

- Tu importación posee el mismo nombre que el del componente? (Chequea el nombre de tu componente y que [cumpla con la sintaxis de componentes `.astro`](/es/basics/astro-syntax/#diferencias-entre-astro-y-jsx).)

- Has incluido la extensión en la importación? (Chequea que el archivo del cual importas contiene una extensión, ej.: `.astro`, `.md`, `.jsx`, `.vue`.)
> Nota: la extensión no es necesaria **solo en los archivos `.js(x)` y `.ts(x)`**.

### Mi componente no es interactivo

Si tu componente se renderiza (ver arriba) pero no responde a la interacción del usuario, entonces puede que hayas olvidado utilizar una [directiva `client:*`](/es/reference/directives-reference/#directivas-del-cliente) para hidratar tu componente.

Por defecto, un [componente de framework no es hidratado en el cliente](/es/guides/framework-components/#hidratando-componentes-interactivos). Si no se provee una directiva `client:*`, su HTML es renderizado en la página sin JavaScript.

:::tip
Los [componentes de Astro](/es/basics/astro-components/) son componentes de maquetado compuestos únicamente por HTML y sin ejecución del lado del cliente. Pero puedes utilizar una etiqueta `<script>` en el maquetado de tu componente y enviar JavaScript al navegador que será ejecutado en el ámbito global.
:::

### Cannot find package 'X'

Si ves un aviso `"Cannot find package 'react'"` (o similar) cuando inicializas Astro, significa que necesitas instalar ese paquete en tu proyecto. No todos los gestores de paquetes instalarán las dependencias peer automáticamente. Si estás utilizando Node v16+ y npm, no deberías preocuparte por esta sección.

React, por ejemplo, es una dependencia peer de la integración `@astrojs/react`. Esto significa que deberías instalar los paquetes oficiales de `react` y `react-dom` junto con tu integración. La integración luego utilizará esos paquetes automáticamente.

```shell ins="react react-dom"
# Ejemplo: Instala integraciones y frameworks a la vez
npm install @astrojs/react react react-dom
```
Lee la [guía de integraciones de Astro](/es/guides/integrations-guide/) para instrucciones acerca de cómo agregar renderers de frameworks, herramientas de CSS y otros paquetes en Astro.

### `Astro.glob()` - no matches found

Cuando utilizas `Astro.glob()` para importar archivos, asegúrate de usar la sintaxis correcta de glob para que coincida con los archivos que necesitas utilizar.

#### Rutas de archivos

Por ejemplo, usa `../components/**/*.js` en `src/pages/index.astro` para importar ambos archivos:
- `src/components/MiComponente.js`
- `src/components/includes/MiOtroComponente.js`

#### Valores compatibles

`Astro.glob()` no es compatible con variables dinámicas ni interpolación de strings.

Esto no es un bug en Astro. Esto se debe a una limitación de la [función `import.meta.glob()` de Vite](https://vitejs.dev/guide/features.html#glob-import) la cual solamente soporta strings estáticas.

Una solución alternativa es importar un grupo de archivos que incluya todos los archivos que necesitemos utilizando `Astro.glob()` y luego filtrarlos:

```astro {6-7}
---
// src/components/destacado.astro
const { postSlug } = Astro.props
const rutaAMiArticuloDestacado = `src/pages/blog/${postSlug}.md`

const articulos = await Astro.glob('../pages/blog/*.md');
const miArticuloDestacado = articulos.find(articulo => articulo.file.includes(rutaAMiArticuloDestacado));
---

<p>
    ¡Mira mi artículo favorito, <a href={miArticuloDestacado.url}>{miArticuloDestacado.frontmatter.title}</a>!
</p>
```

### Utilizando Astro con Yarn 2+ (Berry)

Yarn 2+, también conocido como Berry, utiliza una técnica llamada [Plug'n'Play (PnP)](https://yarnpkg.com/features/pnp) para guardar y manipular módulos de Node, lo cual puede [causar problemas](https://github.com/withastro/astro/issues/3450) al inicializar un proyecto nuevo de Astro utilizando `create astro` o al trabajar con Astro. Una solución alternativa es configurar la [propiedad `nodeLinker`](https://yarnpkg.com/configuration/yarnrc#nodeLinker) en `.yarnrc.yml` con el valor `node-modules`:

```yaml title=".yarnrc.yml"
nodeLinker: "node-modules"
```

### Agregar dependencias a Astro en un monorepo

Cuando trabajas con Astro en una configuración de monorepo, las dependencias del proyecto deben agregarse en el archivo `package.json` de cada proyecto por separado.

Sin embargo, es posible que también desees utilizar Astro en la raíz del monorepo (p. ej. [los proyectos Nx recomiendan instalar las dependencias en la raíz](https://github.com/nrwl/nx/issues/3023#issuecomment-630558318)). En este caso, agrega manualmente las dependencias relacionadas con Astro (p. ej. `@astrojs/vue`, `astro-component-lib`) a la sección `vite.ssr.noExternal` de la configuración de Astro para asegurarte de que estas dependencias se instalen y se incluyan correctamente:

```js
// astro.config.mjs
import { defineConfig } from 'astro/config'
export default defineConfig({
  vite: {
    ssr: {
      noExternal: [
        '@astrojs/vue',
        'astro-component-lib',
      ]
    }
  }
})
```

### Usando `<head>` en un componente

En Astro, usar una etiqueta `<head>` funciona de igual manera que cualquier otra etiqueta HTML: no es movida a la parte superior de la página ni se fusiona con la etiqueta `<head>` existente. Por este motivo es que seguramente desees incluir una sola etiqueta `<head>` por página. Recomendamos escribir esta única etiqueta `<head>` y su contenido en un [componente de plantilla](/es/basics/layouts/).

### An unexpected `<script>` or `<style>` is included

Quizás observes que se importan las etiquetas `<script>` o `<style>` de un componente en tu código HTML incluso si dicho componente no aparece en el resultado final. Esto puede suceder, por ejemplo, cuando [componentes renderizados condicionalmente](/es/basics/astro-syntax/#html-dinamico) no son mostrados. 

El proceso de construcción de Astro funciona en el gráfico de módulos: una vez que un componente se incluye en la plantilla, se procesan, optimizan y empaquetan sus etiquetas `<script>` y `<style>`, ya sea que aparezcan en el resultado final o no. Esto no se aplica a los scripts cuando se aplica la directiva `is:inline`.

## Creando reproducciones mínimas

Cuando estés resolviendo problemas en tu código, puede ser útil crear una **reproducción mínima** del problema que puedas compartir. Se trata de un proyecto de Astro más pequeño y simplificado que demuestra el problema que estás experimentando. Contar con una reproducción funcional en un nuevo proyecto ayuda a confirmar que se trata de un problema repetible y no causado por algo más en tu entorno personal o proyecto existente.

Compartir una reproducción mínima es útil cuando solicitas ayuda en nuestros hilos de soporte y a menudo es necesario al presentar un informe de error a Astro.

### Crea un StackBlitz a través de [astro.new](https://astro.new).

Puedes utilizar [astro.new](https://astro.new) para crear un nuevo proyecto de Astro con un solo clic. Para reproducciones mínimas, recomendamos encarecidamente comenzar desde el ejemplo mínimo (vacío) que se ejecuta en [StackBlitz](https://stackblitz.com), con la menor cantidad de código adicional posible.

StackBlitz ejecutará este proyecto de Astro en el navegador, fuera de tu entorno local. También te proporcionará un enlace compartible para que cualquier mantenedor de Astro o miembro del equipo de soporte pueda ver tu reproducción mínima fuera de su propio entorno local. Esto significa que todos están viendo el mismo proyecto, con la misma configuración y dependencias. Esto facilita que otra persona te ayude a solucionar problemas en tu código. Si el problema es reproducible, te permite verificar que el problema reside en el propio código de Astro y puedes sentirte seguro al enviar un informe de error.

Ten en cuenta que no todos los problemas se pueden reproducir en StackBlitz. Por ejemplo, tu problema podría depender de un entorno o administrador de paquetes específicos, o podría involucrar la transmisión de HTML, que no está admitida en StackBlitz. En este caso, crea un nuevo proyecto de Astro mínimo (vacío) utilizando la CLI, reproduce el problema y cárgalo en un repositorio de GitHub. En lugar de compartir una URL de StackBlitz, proporciona un enlace al repositorio de GitHub de tu reproducción mínima.

### Código mínimo

Una vez que tu proyecto vacío esté configurado, sigue los pasos para reproducir el problema.

Esto puede incluir la adición de paquetes, cambios en la configuración y la escritura de código.

Solo debes agregar la cantidad mínima de código necesaria para reproducir el problema. No reproduzcas otros elementos de tu proyecto existente y elimina todo el código que no esté directamente relacionado con el problema.

### Crea un issue

Si puedes reproducir el problema, ¡entonces es el momento de crear un issue y presentar un informe de error!

Ve al repositorio de Astro correspondiente en GitHub y abre un nuevo issue.

La mayoría de los repositorios tienen una plantilla de issues que hará preguntas o requerirá información para poder presentar el informe. Es importante que sigas estas plantillas, ya que si no proporcionas la información que necesitamos, tendremos que pedírtela... ¡y nadie estará trabajando en tu issue!

Incluye el enlace a tu reproducción mínima en StackBlitz (o al repositorio de GitHub, si es necesario).

Comienza con una descripción del comportamiento esperado en comparación con el comportamiento actual para proporcionar contexto sobre el problema. Luego, incluye instrucciones claras y paso a paso sobre cómo replicar el problema en un proyecto de Astro.

## ¿Necesitas más ayuda?

Ven a conversar con nosotros en [Discord](https://astro.build/chat) y explícanos tu problema en el canal `#support`. ¡Estaremos felices de ayudarte!

Visita los [Issues abiertos en Astro](https://github.com/withastro/astro/issues/) para ver si encuentras un problema conocido o para crear un reporte de bug.

También puedes visitar las [Discusiones de RFC](https://github.com/withastro/rfcs/discussions/) para ver si has alcanzado una limitación conocida de Astro, y para chequear si existen propuestas relacionadas con tu caso de uso.
